Crate faer

faer is a general-purpose linear algebra library for Rust, with a focus on high performance for algebraic operations on medium/large matrices, as well as matrix decompositions.

Most of the high-level functionality in this library is provided through associated functions in its vocabulary types: Mat/MatRef/MatMut.

faer is recommended for applications that handle medium to large dense matrices, and its design is not well suited for applications that operate mostly on low dimensional vectors and matrices such as computer graphics or game development. For those purposes, nalgebra and cgmath may provide better tools.

Basic usage

Mat is a resizable matrix type with dynamic capacity, which can be created using Mat::new to produce an empty $0\times 0$ matrix, Mat::zeros to create a rectangular matrix filled with zeros, Mat::identity to create an identity matrix, or Mat::from_fn for the most generic case.

Given a &Mat<E> (resp. &mut Mat<E>), a MatRef<'_, E> (resp. MatMut<'_, E>) can be created by calling Mat::as_ref (resp. Mat::as_mut), which allow for more flexibility than Mat in that they allow slicing (MatRef::get) and splitting (MatRef::split_at).

MatRef and MatMut are lightweight view objects. The former can be copied freely while the latter has move and reborrow semantics, as described in its documentation.

More details about the vocabulary types can be found in each one’s module’s documentation. See also: faer_entity::Entity and complex_native.

Most of the matrix operations can be used through the corresponding math operators: + for matrix addition, - for subtraction, * for either scalar or matrix multiplication depending on the types of the operands.

Example

use faer::{mat, scale, Mat};

let a = mat![
    [1.0, 5.0, 9.0],
    [2.0, 6.0, 10.0],
    [3.0, 7.0, 11.0],
    [4.0, 8.0, 12.0f64],
];

let b = Mat::<f64>::from_fn(4, 3, |i, j| (i + j) as f64);

let add = &a + &b;
let sub = &a - &b;
let scale = scale(3.0) * &a;
let mul = &a * b.transpose();

let a00 = a[(0, 0)];

Matrix decompositions

faer provides a variety of matrix factorizations, each with its own advantages and drawbacks:

Cholesky decomposition

Mat::cholesky decomposes a self-adjoint positive definite matrix $A$ such that $$A = LL^H,$$ where $L$ is a lower triangular matrix. This decomposition is highly efficient and has good stability properties.

An implementation for sparse matrices is also available.

Bunch-Kaufman decomposition

Mat::lblt decomposes a self-adjoint (possibly indefinite) matrix $A$ such that $$P A P^\top = LBL^H,$$ where $P$ is a permutation matrix, $L$ is a lower triangular matrix, and $B$ is a block diagonal matrix, with $1 \times 1$ or $2 \times 2$ diagonal blocks. This decomposition is efficient and has good stability properties.

LU decomposition with partial pivoting

Mat::partial_piv_lu decomposes a square invertible matrix $A$ into a lower triangular matrix $L$, a unit upper triangular matrix $U$, and a permutation matrix $P$, such that $$PA = LU.$$ It is used by default for computing the determinant, and is generally the recommended method for solving a square linear system or computing the inverse of a matrix (although we generally recommend using a faer::linalg::solvers::Solver instead of computing the inverse explicitly).

An implementation for sparse matrices is also available.

LU decomposition with full pivoting

Mat::full_piv_lu Decomposes a generic rectangular matrix $A$ into a lower triangular matrix $L$, a unit upper triangular matrix $U$, and permutation matrices $P$ and $Q$, such that $$PAQ^\top = LU.$$ It can be more stable than the LU decomposition with partial pivoting, in exchange for being more computationally expensive.

QR decomposition

The QR decomposition (Mat::qr) decomposes a matrix $A$ into the product $$A = QR,$$ where $Q$ is a unitary matrix, and $R$ is an upper trapezoidal matrix. It is often used for solving least squares problems.

An implementation for sparse matrices is also available.

QR decomposition with column pivoting

The QR decomposition with column pivoting (Mat::col_piv_qr) decomposes a matrix $A$ into the product $$AP^\top = QR,$$ where $P$ is a permutation matrix, $Q$ is a unitary matrix, and $R$ is an upper trapezoidal matrix.

It is slower than the version with no pivoting, in exchange for being more numerically stable for rank-deficient matrices.

Singular value decomposition

The SVD of a matrix $M$ of shape $(m, n)$ is a decomposition into three components $U$, $S$, and $V$, such that:

• $U$ has shape $(m, m)$ and is a unitary matrix,
• $V$ has shape $(n, n)$ and is a unitary matrix,
• $S$ has shape $(m, n)$ and is zero everywhere except the main diagonal, with nonnegative diagonal values in nonincreasing order,
• and finally:

$$M = U S V^H.$$

The SVD is provided in two forms: either the full matrices $U$ and $V$ are computed, using Mat::svd, or only their first $\min(m, n)$ columns are computed, using Mat::thin_svd.

If only the singular values (elements of $S$) are desired, they can be obtained in nonincreasing order using Mat::singular_values.

Eigendecomposition

Note: The order of the eigenvalues is currently unspecified and may be changed in a future release.

The eigendecomposition of a square matrix $M$ of shape $(n, n)$ is a decomposition into two components $U$, $S$:

• $U$ has shape $(n, n)$ and is invertible,
• $S$ has shape $(n, n)$ and is a diagonal matrix,
• and finally:

$$M = U S U^{-1}.$$

If $M$ is hermitian, then $U$ can be made unitary ($U^{-1} = U^H$), and $S$ is real valued.

Depending on the domain of the input matrix and whether it is self-adjoint, multiple methods are provided to compute the eigendecomposition:

• Mat::selfadjoint_eigendecomposition can be used with either real or complex matrices, producing an eigendecomposition of the same type.
• Mat::eigendecomposition can be used with either real or complex matrices, but the output complex type has to be specified.
• Mat::complex_eigendecomposition can only be used with complex matrices, with the output having the same type.

If only the eigenvalues (elements of $S$) are desired, they can be obtained in nonincreasing order using Mat::selfadjoint_eigenvalues, Mat::eigenvalues, or Mat::complex_eigenvalues, with the same conditions described above.

Crate features

• std: enabled by default. Links with the standard library to enable additional features such as cpu feature detection at runtime.
• rayon: enabled by default. Enables the rayon parallel backend and enables global parallelism by default.
• serde: Enables serialization and deserialization of Mat.
• npy: Enables conversions to/from numpy’s matrix file format.
• perf-warn: Produces performance warnings when matrix operations are called with suboptimal data layout.
• nightly: Requires the nightly compiler. Enables experimental SIMD features such as AVX512.

Re-exports

• pub use col::Col;
• pub use col::ColMut;
• pub use col::ColRef;
• pub use mat::Mat;
• pub use mat::MatMut;
• pub use mat::MatRef;
• pub use row::Row;
• pub use row::RowMut;
• pub use row::RowRef;
• pub use dyn_stack;
• pub use reborrow;

Modules

• col
  Column vector type.
• complex_native
  Native complex floating point types whose real and imaginary parts are stored contiguously.
• diag
  Diagonal matrix type.
• iostd
  De-serialization from common matrix file formats.
• linalg
  Linear algebra module.
• mat
  Matrix type.
• modulesDeprecated
  Re-exports.
• perm
  Permutation matrices.
• prelude
  faer prelude. Includes useful types and traits for solving linear systems.
• row
  Row vector type.
• solversDeprecated
  Matrix solvers and decompositions.
• sparse
  Sparse data structures and algorithms. Sparse matrix data structures.
• statsrand
  Statistics-related utilities.
• utils
  Various utilities for low level implementations in generic code.

Macros

• assert_matrix_eqstd
  Compare matrices for exact or approximate equality.
• col
  Creates a col::Col containing the arguments.
• concat
  Concatenates the matrices in each row horizontally, then concatenates the results vertically.
• dbgf
  Similar to the dbg macro, but takes a format spec as a first parameter.
• mat
  Creates a Mat containing the arguments.
• row
  Creates a row::Row containing the arguments.
• unzipped
  Used to undo the zipping by the zipped! macro.
• zipped
  Zips together matrix of the same size, so that coefficient-wise operations can be performed on their elements.

Structs

• Scale
  Factor for matrix-scalar multiplication.

Enums

• Conj
  Whether a matrix should be implicitly conjugated when read or not.
• Parallelism
  Parallelism strategy that can be passed to most of the routines in the library.
• Side
  Specifies whether the triangular lower or upper part of a matrix should be accessed.

Traits

• ComplexField
  Unstable trait containing the operations that a number type needs to implement.
• Conjugate
  Trait for types that may be implicitly conjugated.
• Entity
  Unstable core trait for describing how a scalar value may be split up into individual component.
• Index
  Trait for unsigned integers that can be indexed with.
• RealField
  Unstable trait containing the operations that a real number type needs to implement.
• SignedIndex
  Trait for signed integers corresponding to the ones satisfying Index.
• SimpleEntity

Functions

• disable_global_parallelism
  Causes functions that access global parallelism settings to panic.
• get_global_parallelism
  Gets the global parallelism settings.
• scale
  Returns a factor for matrix-scalar multiplication.
• set_global_parallelism
  Sets the global parallelism settings.